Loader Cache Build Failure Fixes - #39

Description of the Change

Stacked on #35 (branches from fix/issue-30-autoloader-cache-refresh); this PR targets that branch, not develop. It closes the last path by which a stale cache could still reach a server, and resolves review nits on #35.

Build command

This covers unlikely edge cases, where a cache is rebuilt in place versus an existing build and there are permissions or space issues.

generate_cache() now verifies a non-empty cache file exists after writing and throws otherwise. Spatie's file driver discards the return values of mkdir()/file_put_contents(), so an un-writable target or a full disk produced only PHP warnings: the command printed Cached N class(es) and exited 0 having written nothing. A pipeline that does not clean would then deploy the previous build's cache — issue #30 again, now with a build artifact's authority.

Existing cache files are cleared before the write, so a failed rebuild in a writable location leaves nothing behind. Where the cache directory itself is un-writable the old file cannot be removed at all; there the guarantee is the non-zero exit, which stops the pipeline before it can ship the stale cache.

Test isolation

The trait-level @runTestsInSeparateProcesses is inherited and in effect — PHPUnit merges annotations from used traits into the class's own. A comment added in #36 claimed otherwise; corrected, so the annotation is not removed as dead weight. test_disable_constant_forces_live_discovery now carries its own @runInSeparateProcess, as its define() is process-wide and cannot be undone. setAccessible() calls dropped: no effect since PHP 8.1, deprecated in 8.5.

Nits

• i18n text domains standardised on tenup-plugin, matching the rest of the package.
• Trimmed the get_classes() cache/live fallback comments to concise statements.
• Upgrade Guide lists the five status badges the debug page actually renders.
• Debugging notes that a tenup_framework_cache_load_failed listener must be registered before the failing loader runs, so full coverage needs an mu-plugin.

Refs #30 — #35 carries the fix for the issue; this PR hardens the build path it introduced.

How to test the Change

1. composer lint, composer static (PHPStan level 10) and composer test — all green (65 tests / 181 assertions).
2. Build a cache, then make the target un-writable and rebuild:

   composer generate-class-cache -- <dir>   # writes class-loader-cache/class-loader-cache-v2.php
   chmod 555 <dir>
   composer generate-class-cache -- <dir>; echo $?

   Before this PR: Cached N class(es), exit 0, no file written. After: Failed to write the class cache to "…", exit 1.
3. With a cache already present and class-loader-cache/ made un-writable, rebuild: exit 1 with Could not remove the existing class cache at "…", rather than a green build over a stale file.
4. In wp-admin, confirm the badges on admin.php?page=tenup-framework-loaders match the five listed in the Upgrade Guide.

Local runs on PHP 8.5: three process-isolated tests error on an antecedent/patchwork deprecation flood, unrelated to this change. Green on 8.3.

Changelog Entry

Changed - generate_cache() fails with a RuntimeException (a non-zero exit from the build command) when no cache file was written, instead of reporting success. Any cache in a writable location is cleared before the write, so a failed rebuild cannot leave a stale file behind.
Developer - Build-command tests for un-writable targets and caches that cannot be replaced; corrected test-isolation annotations and removed no-op setAccessible() calls; i18n text domains standardised on tenup-plugin; Upgrade Guide badge list and Debugging hook-timing note corrected.

Credits

Props @rleeson, @darylldoyle

Checklist:

• I agree to follow this project's Code of Conduct.
• I have updated the documentation accordingly.
• I have added Critical Flows, Test Cases, and/or End-to-End Tests to cover my change.
• All new and existing tests pass.